"""
框架核心异常处理模块

此模块定义了 Axiom Boot 框架的层次化异常体系及相应的全局异常处理器。
"""
import logging
from typing import Any, TYPE_CHECKING

from fastapi import Request
from fastapi.responses import JSONResponse

if TYPE_CHECKING:
    from fastapi import FastAPI

from axiom_boot.api.models import ApiResponse


logger = logging.getLogger(__name__)


class AxiomException(Exception):
    """
    框架所有自定义异常的统一基类。
    """
    def __init__(self, message: str):
        super().__init__(message)
        self.message = message


# =============================================================================
# 框架内部异常 (通常表示编程或配置错误，应导致程序快速失败)
# =============================================================================

class FrameworkException(AxiomException):
    """
    所有框架内部错误的基类。
    """
    pass


class ServiceNotFoundException(FrameworkException):
    """
    当 DI 容器无法找到请求的服务时抛出。
    """
    pass


class CircularDependencyError(FrameworkException):
    """
    当 DI 容器在解析服务时检测到循环依赖时抛出。
    """
    def __init__(self, resolution_stack: list[str]):
        path = " -> ".join(resolution_stack)
        super().__init__(
            f"Circular dependency detected: {path}. "
            "Please break the cycle by using constructor/method injection "
            "for one of the services or by refactoring your dependencies."
        )


class ConfigurationException(FrameworkException):
    """
    当配置解析或验证失败时抛出。
    """
    pass


class DatabaseException(FrameworkException):

    """
    当数据库操作失败时抛出。
    """
    pass


# =============================================================================
# 业务逻辑与 HTTP 状态异常
# =============================================================================

class BusinessException(AxiomException):
    """
    所有业务逻辑异常的基类 (HTTP 200, code=400)。

    业务异常是可预期的，并会被全局异常处理器转换为标准的 API 响应。
    """
    def __init__(self, message: str, data: Any = None):
        super().__init__(message)
        self.data = data


class NotFoundException(BusinessException):
    """当业务数据未找到时抛出。这是一种业务异常。"""
    def __init__(self, message: str = "资源不存在"):
        super().__init__(message=message)


class PermissionDenied(AxiomException):
    """当用户无权访问资源时抛出 (HTTP 403)"""
    def __init__(self, message: str = "权限不足"):
        super().__init__(message=message)


class Unauthorized(AxiomException):
    """当请求需要认证但未提供或认证失败时抛出 (HTTP 401)"""
    def __init__(self, message: str = "认证失败"):
        super().__init__(message=message)


class BadRequest(BusinessException):
    """当请求无效或格式错误时抛出"""
    def __init__(self, message: str = "请求参数错误", data: Any = None):
        super().__init__(message=message, data=data)


class AIException(BusinessException):
    """当 AI 服务调用过程中发生可预期的业务错误时抛出"""
    def __init__(self, message: str = "AI 服务发生错误", data: Any = None):
        super().__init__(message=message, data=data)


# =============================================================================
# 全局异常处理器
# =============================================================================

async def framework_exception_handler(request: Request, exc: FrameworkException) -> JSONResponse:
    """
    处理所有框架内部异常。
    返回标准的 HTTP 500 响应，表示服务器内部错误。
    """
    logger.error(f"捕获到框架内部严重错误: {exc.message}", exc_info=True)
    return JSONResponse(
        status_code=500,
        content=ApiResponse.fail(code=500, message="服务器内部错误，请联系管理员").model_dump(),
    )


async def business_exception_handler(request: Request, exc: BusinessException) -> JSONResponse:
    """
    统一处理所有 BusinessException 及其子类。
    
    此处理器遵循API响应规范：
    - HTTP状态码总是返回 200 OK。
    - 响应体中的 'success' 为 false。
    - 响应体中的 'code' 固定为 400，表示业务逻辑错误。
    - 具体的错误信息在 'message' 字段中描述。
    """
    logger.warning(f"捕获到业务异常: {exc.message}", exc_info=False)
    return JSONResponse(
        status_code=200,  # 业务异常总是返回 200 OK
        content=ApiResponse.fail(
            code=400,  # 业务错误统一使用 400
            message=exc.message,
            data=exc.data
        ).model_dump()
    )


async def unauthorized_exception_handler(request: Request, exc: Unauthorized) -> JSONResponse:
    """
    处理认证失败异常 (Unauthorized)。
    返回标准的 HTTP 401 响应。
    """
    logger.warning(f"捕获到认证异常: {exc.message}", exc_info=False)
    return JSONResponse(
        status_code=401,
        content=ApiResponse.fail(code=401, message=exc.message).model_dump(),
        headers={"WWW-Authenticate": "Bearer"},
    )


async def permission_denied_exception_handler(request: Request, exc: PermissionDenied) -> JSONResponse:
    """
    处理权限不足异常 (PermissionDenied)。
    返回标准的 HTTP 403 响应。
    """
    logger.warning(f"捕获到权限异常: {exc.message}", exc_info=False)
    return JSONResponse(
        status_code=403,
        content=ApiResponse.fail(code=403, message=exc.message).model_dump(),
    )


def register_exception_handlers(app: "FastAPI"):
    """
    向 FastAPI 应用实例注册所有预定义的全局异常处理器。
    """
    app.add_exception_handler(FrameworkException, framework_exception_handler)
    app.add_exception_handler(BusinessException, business_exception_handler)
    app.add_exception_handler(Unauthorized, unauthorized_exception_handler)
    app.add_exception_handler(PermissionDenied, permission_denied_exception_handler)
    logger.info("全局业务、认证、授权、框架内部异常处理器已注册。") 